home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / g_man / cat3 / ftn / readdi.z / readdi
Encoding:
Text File  |  1998-10-20  |  7.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4. rrrreeeeaaaaddddddddiiii((((3333GGGG))))                                                          rrrreeeeaaaaddddddddiiii((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      rrrreeeeaaaaddddddddiiii - reads a rectangular screen region, returning displayed pixel
  10.      colors in a packed RGB format.
  11.  
  12. FFFFOOOORRRRTTTTRRRRAAAANNNN 77777777 SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  13.      ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee rrrreeeeaaaaddddddddiiii((((xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222,,,, nnnneeeewwwwxxxx,,,,
  14.      iiiinnnntttteeeeggggeeeerrrr****4444 xxxx1111,,,, yyyy1111,,,, xxxx2222,,,, yyyy2222,,,, hhhhiiiinnnnttttssss
  15.      iiiinnnntttteeeeggggeeeerrrr****4444 ppppaaaarrrrrrrraaaayyyy((((****))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  18.      _x_1     expects the x screen coordinate of one corner of the rectangle.
  19.  
  20.      _y_1     expects the y screen coordinate of one corner of the rectangle.
  21.  
  22.      _x_2     expects the x screen coordinate of the opposite corner of the
  23.             rectangle.
  24.  
  25.      _y_2     expects the y screen coordinate of the opposite corner of the
  26.             rectangle.
  27.  
  28.             These coordinates are relative to the lower-left pixel on the
  29.             screen, whose coordinates are 0,0.  It does not matter whether x1
  30.             is greater than or less than x2, nor y1 greater than or less than
  31.             y2.
  32.  
  33.             The rectangle specification is inclusive.  Thus the rectangle
  34.             specified by coordinates 5,10,14,6 is 10 pixels wide and 5 pixels
  35.             high.
  36.  
  37.      _p_a_r_r_a_y expects the array that is to receive the pixels that are read.
  38.             Pixels are returned in packed ABGR format, with red occupying the
  39.             lower 8 bits and alpha (if available) occupying the upper 8 bits.
  40.             Returned alpha is one (0xff) if the pixel is in color index mode
  41.             or if no alpha bitplanes are present.  Return order is left-to-
  42.             right, then bottom-to-top, i.e.
  43.  
  44.  
  45.  
  46.                      6  7  8
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. rrrreeeeaaaaddddddddiiii((((3333GGGG))))                                                          rrrreeeeaaaaddddddddiiii((((3333GGGG))))
  71.  
  72.  
  73.  
  74.                      3  4  5
  75.  
  76.  
  77.  
  78.                                0  1  2
  79.  
  80.  
  81.                _h_i_n_t_s
  82.                     hints is an unsigned long passed to rrrreeeeaaaaddddddddiiii which serves as
  83.                     a bit mask for enabling the various rrrreeeeaaaaddddddddiiii modifiers
  84.                     delineated in the list of constants below.  The constants
  85.                     are specified by bitwise ORing them, or by adding them.
  86.                     For example,
  87.  
  88.                     readdi(0,0,99,99,parray,(RDFREZ + RDALPH))
  89.  
  90.                     blocks graphics while reading the display and returns an
  91.                     image in which alpha is equal to one.
  92.  
  93.                     These modifiers are hints, not directives, and are
  94.                     therefore ignored by systems that do not support the
  95.                     requested feature.
  96.  
  97.                     The following hints are available:
  98.  
  99.                     RRRRDDDDFFFFRRRREEEEZZZZ freezes the screen by blocking all graphics calls
  100.                     until the read is completed.  This assures that the
  101.                     returned data accurately represents what was being
  102.                     displayed at the time of the call.
  103.  
  104.                     If graphics calls are allowed to proceed while rrrreeeeaaaaddddddddiiii is
  105.                     executing, it is possible that the returned data may not
  106.                     resemble what was displayed at the time of execution,
  107.                     since drawing commands and commands that affect the
  108.                     display state ( etc.) can change the displayed data while
  109.                     it is being read.
  110.  
  111.                     RRRRDDDDAAAALLLLPPPPHHHH returns all alpha values set to one (represented as
  112.                     0xff in the color space of this command).
  113.  
  114.                     If not requested, actual alpha values are returned if
  115.                     alpha planes are installed and the pixel is in RGB mode.
  116.                     One (0xff) is returned for pixels in color index mode or
  117.                     if no alpha planes are installed.
  118.  
  119.                     RRRRDDDDIIIIGGGGPPPPUUUU ignores the contents of the pop-up framebuffer.
  120.  
  121.                     RRRRDDDDIIIIGGGGOOOOVVVV ignores the contents of the overlay framebuffer.
  122.  
  123.                     RRRRDDDDIIIIGGGGOOOOVVVV ignores the contents of the underlay framebuffer.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. rrrreeeeaaaaddddddddiiii((((3333GGGG))))                                                          rrrreeeeaaaaddddddddiiii((((3333GGGG))))
  137.  
  138.  
  139.  
  140.                     RRRRDDDDOOOOFFFFFFFFSSSS Data read beyond the framebuffer boundary is
  141.                     returned equal to zero, regardless of the setting of this
  142.                     hint.  Reading beyond the framebuffer boundary may reduce
  143.                     performance.
  144.  
  145. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  146.      rrrreeeeaaaaddddddddiiii generates the displayed value of each addressed pixel, taking into
  147.      account all display bitplanes and modes except those of the cursor.  The
  148.      ABGR values returned therefore correspond to the values viewed on the
  149.      monitor, with the following exceptions:
  150.  
  151.           1. The returned values are not gamma corrected.
  152.  
  153.           2. The cursor will not appear in the returned data.
  154.  
  155.           3. If either of the hints RDIGUN, RDIGOV, or RDIGPU is set, the
  156.           corresponding framebuffer data will not be included in the returned
  157.           data.
  158.  
  159. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  160.      rrrreeeeaaaaddddddddiiii returns the number of pixels read.
  161.  
  162. NNNNOOOOTTTTEEEESSSS
  163.      This subroutine is available only in immediate mode.
  164.  
  165. BBBBUUUUGGGGSSSS
  166.      On IRIS-4D VGX and VGXT models, rrrreeeeaaaaddddddddiiii does not correctly read the
  167.      underlay planes when the program is double buffered.
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.